home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 18 / CU Amiga Magazine's Super CD-ROM 18 (1997)(EMAP Images)(GB)[!][issue 1998-01].iso / CUCD / Programming / AmigaE / Src / OOmodules / object.e < prev    next >
Encoding:
Text File  |  1997-05-03  |  12.2 KB  |  492 lines
  1. /****** object/--background-- ******************************************
  2.  
  3.     PURPOSE
  4.         The base object for everything in the oomodules/ hierarchy.
  5.  
  6.     CREATION
  7.         in early 1995 by Trey van Riper
  8.  
  9.     HISTORY
  10.  
  11. ******************************************************************************
  12.  
  13. History
  14.  
  15.  
  16. */
  17.  
  18. OPT MODULE
  19. OPT EXPORT,PREPROCESS
  20.  
  21. #define LOCALE_SUPPORT 1
  22.  
  23.  
  24. /* MODULE  'other/stderr' */
  25.  
  26. #ifdef LOCALE_SUPPORT
  27.  
  28. MODULE  'oomodules/library/locale/catalogList',
  29.         'oomodules/old'
  30.  
  31. EXPORT DEF catalogList:PTR TO catalogList
  32.  
  33. #endif
  34.  
  35.  
  36. OBJECT object
  37. /****** object/--object-- ******************************************
  38.  
  39.     NAME
  40.         object
  41.  
  42.     NOTES
  43.         The Object object (hmm.. sounds redundant) has no attributes, and
  44.         tons of methods.
  45.  
  46.         We may decide to create one or two very important global variables
  47.         in the future.  These variables will hold information on various
  48.         system settings which will allow a smoother halt() and some other
  49.         handy functions.  At the moment, though, no global variables exist
  50.         in the Object module.
  51.  
  52. ******************************************************************************
  53.  
  54. History
  55.  
  56.  
  57. */
  58. ENDOBJECT
  59.  
  60. PROC new(opts=0) OF object
  61. /****** object/new ******************************************
  62.  
  63.     NAME
  64.         new() -- Create a new instance of an object.
  65.  
  66.     SYNOPSIS
  67.         object.new(opts=0)
  68.  
  69.     FUNCTION
  70.         This allows new instances of objects to be created.  It takes as
  71.         an argument an Amiga E list ['such','as','this'] which is then
  72.         parsed by the opts() method, which places a call to the select()
  73.         method.  My might want to read up on those.
  74.  
  75.         In general, you will only want to create new select() statements
  76.         for your objects... new() most likely can be left alone.
  77.  
  78.     INPUTS
  79.         opts=0 -- The optionlist
  80.  
  81.     EXAMPLE
  82.         When folks go to use objects, they ought to do something like the
  83.         following:
  84.  
  85.           NEW object.new()
  86.  
  87.         or if there are options to parse...
  88.  
  89.           NEW object.new(["boo",'SCREAM'])
  90.  
  91.     SEE ALSO
  92.         select(), init()
  93. ******************************************************************************
  94.  
  95. History
  96.  
  97.  
  98. */
  99.  /*
  100.   * NEW the global catalog list. Don't do it in init() for it could be needed
  101.   * in there...
  102.   */
  103.  
  104. #ifdef LOCALE_SUPPORT
  105.  
  106.   IF catalogList = NIL THEN NEW catalogList.new()
  107.  
  108. #endif
  109.  
  110.  
  111.   self.init()
  112.   self.opts(opts)
  113.  
  114. ENDPROC
  115.  
  116. PROC init() OF object IS EMPTY
  117. /****** object/init ******************************************
  118.  
  119.     NAME
  120.         init() -- Initialize an object.
  121.  
  122.     SYNOPSIS
  123.         object.init()
  124.  
  125.     FUNCTION
  126.         Initializes an object to default startup values.  You very likely
  127.         will want to create your own init() method in your derived objects,
  128.         in order to properly initialize your attributes.  This init()
  129.         method does nothing.  If you're not concerned about the internal
  130.         attributes during initialization, then this method can be left
  131.         alone.
  132.  
  133.     SEE ALSO
  134.         new(), select()
  135. ******************************************************************************
  136.  
  137. History
  138.  
  139.  
  140. */
  141.  
  142.  
  143. PROC size() OF object IS 4
  144. /****** object/size ******************************************
  145.  
  146.     NAME
  147.         size() -- Get the size of the object in bytes
  148.  
  149.     SYNOPSIS
  150.         object.size()
  151.  
  152.     FUNCTION
  153.         This returns the SIZEOF the current object.  Most likely, this is
  154.         a superfluous method, and might need to be reconsidered.  In the
  155.         meantime, if you want this method to have any meaning at all, you
  156.         need to calculate the 'SIZEOF' your object either by adding up all
  157.         the attributes and adding four more bytes (for the pointer to its
  158.         methods), or by compiling the object and using ShowModule to see
  159.         the SIZEOF it comes up with.
  160.  
  161.     RESULT
  162.         The size in bytes
  163.  
  164. ******************************************************************************
  165.  
  166. History
  167.  
  168.  
  169. */
  170.  
  171. PROC opts(opts) OF object
  172. /****** object/opts ******************************************
  173.  
  174.     NAME
  175.         opts() -- Parse options.
  176.  
  177.     SYNOPSIS
  178.         object.opts(optionlist)
  179.  
  180.     FUNCTION
  181.         This runs a FOR/ENDFOR loop that calls select().  It's most
  182.         unlikely that you'll need to modify this method. This method
  183.         may disappear in the future (it might be absorbed by new()).
  184.  
  185.     INPUTS
  186.         optionlist -- The optionlist to parse.
  187.  
  188.     SEE ALSO
  189.         select(), new()
  190. ******************************************************************************
  191.  
  192. History
  193.  
  194.  
  195. */
  196.  DEF i,next
  197.  IF opts=0 THEN RETURN
  198.  next:=opts
  199. -> REPEAT
  200.   FOR i:=0 TO ListLen(next)-1
  201.    i:=self.select(next,i)
  202.   ENDFOR
  203. ->  next:=Next(next)
  204. -> UNTIL next=NIL
  205. ENDPROC
  206.  
  207. PROC select(opt,i) OF object IS i
  208. /****** object/select ******************************************
  209.  
  210.     NAME
  211.         select() -- Selection of action on initialization.
  212.  
  213.     SYNOPSIS
  214.         object.select(optionlist,index)
  215.  
  216.     FUNCTION
  217.         You'll definately want to create a 'select' statement if you want
  218.         new() to have options enabled.  All select statements should have
  219.         this general format:
  220.  
  221.         PROC select(optionlist,index) OF myBlowOutObject
  222.         DEF item
  223.           item:=ListItem(optionlist,index)
  224.           SELECT item
  225.             -> various cases and perhaps a default.. could look like this:
  226.             CASE "boo"
  227.            INC index
  228.            self.boo(ListItem(optionlist,index))
  229.           ENDSELECT
  230.         ENDPROC i
  231.  
  232.         NOTE THE LAST LINE!  If you fail to return i, you could wind up
  233.         with an endless loop!  This would be a bad thing.
  234.  
  235.     INPUTS
  236.         optionlist -- An elist with tags (or options) that define object
  237.             specific actions.
  238.  
  239.         index -- Position of item we process next in the list.
  240.  
  241.     SEE ALSO
  242.         new(), init()
  243. ******************************************************************************
  244.  
  245. History
  246.  
  247.  
  248. */
  249.  
  250. PROC error(string,number) OF object
  251. /****** object/error ******************************************
  252.  
  253.     NAME
  254.         error() -- Report error to stderr
  255.  
  256.     SYNOPSIS
  257.         object.error(string,number)
  258.  
  259.     FUNCTION
  260.         This calles err_WriteF(a,b) as it stands, and returns NIL. You may
  261.         want to overload this behavior to do something else, or perhaps
  262.         call this from within your own error() routine via SUPER.  The
  263.         err_WriteF() procedure was written by Joseph E. Van Riper III as
  264.         an easy kind of standard error port for Amiga E... it should be
  265.         found in the emodules:other directory of your structure. If you
  266.         don't have it, you can get it from aminet:dev/e.
  267.  
  268.         If err_WriteF() is ever called, the programmer must end hir main()
  269.         program with 'err_Dispose()' before exiting.  This is due to
  270.         certain housekeeping matters in Van Riper's StdErr port.
  271.  
  272.     INPUTS
  273.         string -- String to report.
  274.  
  275. ******************************************************************************
  276.  
  277. History
  278.  
  279.  
  280. */
  281.  /* err_WriteF(string,[number]) */
  282.  RETURN NIL
  283. ENDPROC
  284.  
  285. PROC name() OF object IS 'Object'
  286. /****** object/name ******************************************
  287.  
  288.     NAME
  289.         name() -- Get the name of the object.
  290.  
  291.     SYNOPSIS
  292.         object.name()
  293.  
  294.     FUNCTION
  295.         This method should be overloaded for each new class.  It should
  296.         return a short string of the name of the object.  In the object
  297.         Object, it's called 'Object'.  This is useful for trying to track
  298.         down certain internal things in the system (particularly some of
  299.         the really funky stuff in the Numbers hierarchy).
  300.  
  301.     RESULT
  302.         A string with the name of the object.
  303.  
  304. ******************************************************************************
  305.  
  306. History
  307.  
  308.  
  309. */
  310.  
  311. PROC end() OF object IS EMPTY
  312. /****** object/end ******************************************
  313.  
  314.     NAME
  315.         end() -- Global destructor.
  316.  
  317.     SYNOPSIS
  318.         object.end()
  319.  
  320.     FUNCTION
  321.         This is the automatic deallocator.  Whenever an object is ENDed,
  322.         this will be called.  While the Object's end() statement does
  323.         nothing, other objects in the hierarchy may be doing some kind
  324.         of housekeeping before deallocating the object.  If you do not
  325.         know whether or not your parent object needs to do some kind of
  326.         housekeeping, do a SUPER self.end() somewhere within your own
  327.         end() statement (if you even need an end() statement).
  328.  
  329.     SEE ALSO
  330.         new()
  331. ******************************************************************************
  332.  
  333. History
  334.  
  335.  
  336. */
  337.  
  338. PROC derivedClassResponse() OF object
  339. /****** object/derivedClassResponse ******************************************
  340.  
  341.     NAME
  342.         derivedClassResponse() -- Standard proc for derived responsibility.
  343.  
  344.     SYNOPSIS
  345.         object.derivedClassResponse()
  346.  
  347.     FUNCTION
  348.         Call this proc in a method that is non-functional by now, but is
  349.         functional in objects that derive from this. It writes a message
  350.         to stdout that tells that this method isn't implemented.
  351.  
  352. ******************************************************************************
  353.  
  354. History
  355.  
  356.  
  357. */
  358. DEF msg:PTR TO CHAR
  359.  
  360. #ifdef LOCALE_SUPPORT
  361.  
  362.   IF catalogList
  363.  
  364.     catalogList.setCurrentCatalog(NIL,OLDC_OBJECT, OLDL_ENGLISH)
  365.     msg := catalogList.getString(OLDM_OBJECT_DERIVED_RESPONSE, 'Method not implemented for this derived class')
  366.  
  367.   ELSE
  368. #endif
  369.     msg := 'Method not implemented for this derived class'
  370. #ifdef LOCALE_SUPPORT
  371.   ENDIF
  372. #endif
  373.  
  374.  
  375.   WriteF('\s:\s\n',self.name(), msg)
  376.  
  377. ENDPROC
  378.  
  379. PROC halt(i) OF object
  380. /****** object/halt ******************************************
  381.  
  382.     NAME
  383.         halt() -- Stop program execution immediately.
  384.  
  385.     SYNOPSIS
  386.         object.halt(i)
  387.  
  388.     FUNCTION
  389.         This is intended to stop the entire program dead in its tracks.
  390.         Use this with extreme prejudice, as it doesn't bother to
  391.         deallocate anything (yet), and will likely leave filehandles
  392.         open or memory allocated or any of a hundred other horrible
  393.         system-unfriendly things (it calls CleanUp()).
  394.  
  395.         In the future, this statement will likely be used to Raise() an
  396.         exception rather than die.
  397.  
  398.     INPUTS
  399.         i -- Anything you like. Passed to CleanUp().
  400.  
  401. ******************************************************************************
  402.  
  403. History
  404.  
  405.  
  406. */
  407.  CleanUp(i)
  408. ENDPROC
  409.  
  410. PROC sameAs(a:PTR TO object) OF object IS IF a.name() = self.name() THEN TRUE ELSE FALSE
  411. /****** object/sameAs ******************************************
  412.  
  413.     NAME
  414.         sameAs() -- Compare to another object.
  415.  
  416.     SYNOPSIS
  417.         object.sameAs(obj:PTR TO object)
  418.  
  419.     FUNCTION
  420.         This method determines whether or not the current object is the
  421.         same kind of object as the parameter object.  obj is assumed to
  422.         be in the Object heirarchy at some point. Basically, this simply
  423.         compares self.name() to a.name() to see if it's the same value.
  424.  
  425.     INPUTS
  426.         obj:PTR TO object -- Pointer to any object in the oomodules/
  427.             hierarchy.
  428.  
  429.     RESULT
  430.         TRUE if both objects are the same, FALSE if not.
  431.  
  432. ******************************************************************************
  433.  
  434. History
  435.  
  436.  
  437. */
  438.  
  439. PROC differentFrom(a) OF object IS self.derivedClassResponse()
  440. /****** object/differentFrom ******************************************
  441.  
  442.     NAME
  443.         differentFrom() -- Are the objects not of the same kind?
  444.  
  445.     SYNOPSIS
  446.         object.differentFrom(obj)
  447.  
  448.     FUNCTION
  449.         This method determines whether or not the current object is a
  450.         different kind of object from the parameter object.  obj is
  451.         assumed to be in the Object heirarchy at some point.
  452.  
  453.     INPUTS
  454.         obj -- Pointer to any object in the oomodules/ hierarchy.
  455.  
  456.     RESULT
  457.         TRUE if objects are different, FALSE if the same.
  458.  
  459.     NOTES
  460.         Doesn't do anything by now, derived objects have to handle this.
  461.  
  462. ******************************************************************************
  463.  
  464. History
  465.  
  466.  
  467. */
  468.  
  469. PROC update(a=0) OF object IS self.derivedClassResponse()
  470. /****** object/update ******************************************
  471.  
  472.     NAME
  473.         update() -- Update the object.
  474.  
  475.     SYNOPSIS
  476.         object.update(a)
  477.  
  478.     FUNCTION
  479.         This method currently does nothing, but the idea behind this method
  480.         is to cause the object to update itself (freshen its current
  481.         information, perhaps).
  482.  
  483.     INPUTS
  484.         a -- Use it as you want.
  485.  
  486. ******************************************************************************
  487.  
  488. History
  489.  
  490.  
  491. */
  492.